Repository navigation
Add maintain commands for deployed-app items - #62
Draft
raghubetina wants to merge 2 commits into
Draft
raghubetina wants to merge 2 commits into
raghubetina wants to merge 2 commits into
Conversation
raghubetina
force-pushed
the
maintain-command
branch
3 times, most recently
from
November 17, 2026 07:39
f9ab7cb to
cfcbf02
Compare
The maintenance service (firstdraft/firstdraft#1290) gives the owner's agent a queue of open items for each deployed Environment. The agent needs to read that queue, see one item's evidence, and record how it was resolved, so this adds firstdraft maintain, maintain show, and maintain resolve against the API contract 0.8.1 routes. Each response is checked against the exact contract and printed as a fresh copy, so nothing unvalidated reaches stdout, while the evidence's untrusted list and note pass through unchanged for the agent. The Service refuses a second resolution with item_already_resolved, so a repeat is safe and an unconfirmed resolution is maintain_unavailable, not request_outcome_unknown. The CLI never reads FirstDraft-API-Contract at run time, so only the release check keeps this package from shipping ahead of a Service with these routes. The required range rises to >= 0.8.1. The other commands behave the same against a 0.8.0 Service; a range per command would need a new compatibility format in all three repositories. Only reads are called safe to retry. A recurrence can reopen an item between a lost resolution response and its retry, so after an unconfirmed resolution the agent rereads it with `maintain show`.
raghubetina
force-pushed
the
maintain-command
branch
from
November 17, 2026 07:44
cfcbf02 to
dab476c
Compare
raghubetina
force-pushed
the
maintain-command
branch
2 times, most recently
from
November 17, 2026 16:41
82422fc to
30d3418
Compare
First Draft files and keeps a GitHub issue current for every item, as Rollbar's and Honeybadger's GitHub integrations do. Summaries now carry `issue_url`, so the agent can link the issue from its pull request without managing the issue itself.
raghubetina
force-pushed
the
maintain-command
branch
from
November 17, 2026 18:27
30d3418 to
4eab83d
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the
firstdraft maintaingroup for the maintenance service in firstdraft/firstdraft#1290 (draft, API contract 0.8.1). Part of the maintenance package; draft until the owner reviews the package as a whole.firstdraft maintain [--environment NAME] [--page N]reads one page of open items for the Project in.firstdraft/state.json(GET .../environments/:name/items?page=N).--environmentdefaults toproduction.firstdraft maintain show ID [--environment NAME]reads one item withevidenceanddone_when.firstdraft maintain resolve ID --reason REASON [--detail TEXT] [--environment NAME]posts{reason, detail?}. A reason other thanpull_request,host_change,not_a_bug,duplicate, orstopped_occurringisinvalid_arguments(exit 2) before any request.All three accept
--staging, authenticate throughauthenticateApiCommand, use the pinned origin, and print the validated response on stdout. Validation is exact-key, likecompilation cancel: the Project ID, Environment name, and item ID must match the request, index items must be open, and a resolution must come back resolved with the sent reason. The CLI prints a fresh copy, soevidence.untrustedandevidence.notereach the agent unchanged.New handled errors, in
docs/errors.md:maintain_rejected: a validated problem (environment_not_found,item_not_found,invalid_resolution_reason,item_already_resolved), withresponse.maintain_unavailable: network failure, timeout, 408/5xx, or an error with no problem body. The Service refuses a second resolution, so retrying is safe; this follows thecompilation_cancel_unavailableprecedent rather thanrequest_outcome_unknown.invalid_maintain_response: a success response that breaks the contract.Contract range (owner review)
The CLI never reads
FirstDraft-API-Contractat run time.release/compatibility.jsondeclares one range per CLI release, and the Service's release check compares it with Production. This PR raisesrequires.api_contractfrom>= 0.8.0to>= 0.8.1(keeping< 0.9.0), as step 7 of the add-a-command checklist says.>= 0.8.0would let the release check publish a CLI whosemaintaincannot work. Against a 0.8.0 Service the routes do not exist and Rails answers 404 HTML without the contract header, so a run-time header check could not help. That case ismaintain_unavailablewithstatus: 404, anddocs/errors.mdexplains it.firstdraft.release-compatibilityformat in all three repositories.The version stays 0.9.0; the version PR picks the next one.
Sibling changes
firstdraft/skills: addsrc/commands/maintain.jstopackedFileAllowlistinscript/cli-contract/config.mjs, raise the Skills API requirement to>= 0.8.1when it bundles this CLI, and add the Skill'smaintainguidance and error handling.Docs: updated docs/commands.md (intro, command map, Maintain section, Service endpoints, add-a-command checklist), docs/errors.md (Maintenance recovery and the Error index rows), and README.md.
Review: Codex, approve (3 rounds, 2 findings fixed)
Validation
npm audit: 0 vulnerabilitiesnpm run check: passes (284 tests, pack check, packed smoke includingmaintain,show, andresolveagainst a local server)Observed (2026-11-17): against a local service from firstdraft/firstdraft#1290 polling
learn's production GlitchTip data,maintain,maintain show,maintain resolve, and a repeated resolve (409) behaved as documented; the run found the missingevidence.request.host, now added.Second commit: summaries carry the nullable
issue_url, the GitHub issue First Draft files and keeps current for the item (firstdraft/firstdraft#1296). The service files issues itself through the GitHub App (owner direction, 2026-11-17), so the CLI has no issue command.Review (second commit): Codex, approve (1 round, no findings; an earlier
maintain issuedesign went through 3 rounds before the direction changed)